home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 June / EnigmA AMIGA RUN 08 (1996)(G.R. Edizioni)(IT)[!][issue 1996-06][EARSAN CD VII].iso / earcd / utmisc2 / fiflb382.lha / fifolib.doc < prev    next >
Text File  |  1996-03-27  |  13KB  |  391 lines
  1.  
  2.                   FIFO.LIBRARY
  3.  
  4.             MANUAL, VERSION 37.4 -- 38.2
  5.  
  6.                 By: Matthew Dillon
  7.  
  8. TABLE OF CONTENTS
  9.  
  10. fifo.library/--FifoNotes--
  11. fifo.library/OpenFifo
  12. fifo.library/CloseFifo
  13. fifo.library/ReadFifo
  14. fifo.library/WriteFifo
  15. fifo.library/RequestFifo
  16. fifo.library/BufSizeFifo
  17. fifo.library/--FifoNotes--                fifo.library/--FifoNotes--
  18.  
  19.     FIFO.LIBRARY is a general fifo library implementation with the following
  20.     features:
  21.  
  22.     * named fifos
  23.     * support for writing to a fifo from a hardware exception
  24.     * multiple readers on a fifo supported, each get the same data
  25.       stream
  26.     * efficient reading (no buffer copies on read)
  27.     * automatic or manual (via message passing) flow control
  28.  
  29.     The uses for this library are limitless.  To use the library, open
  30.     it via OpenLibrary("fifo.library", 0);, the base variable is named:
  31.  
  32.     FifoBase
  33.  
  34.     Please refer to the test program for an example of usage.
  35.  
  36.     LINK LIBRARIES:
  37.     fifo.lib    standard amiga (join type) library,
  38.             large-data model
  39.  
  40.     fifos.lib   standard amiga (joing type) library,
  41.             small-data model
  42.  
  43.     fifosr.lib  standard amiga (joing type) library,
  44.             small-data model, registered arguments
  45.  
  46.  
  47. fifo.library/OpenFifo                      fifo.library/OpenFifo
  48.  
  49.     NAME
  50.     OpenFifo - open a rendezvous FIFO by name
  51.  
  52.     SYNOPSIS
  53.     fifo = OpenFifo(name, bufsize, flags)
  54.     D0         D0    D1     A0
  55.  
  56.     void *fifo;    /*  returned fifo handle        */
  57.     char *name;    /*  rendezvous name - case sensitive    */
  58.     long bufsize;    /*  must be a power of 2        */
  59.     long flags;    /*  open flags                */
  60.  
  61.     FUNCTION
  62.     OpenFifo() creates a FIFO if <name> does not exist, else
  63.     references an already existing FIFO named <name>.  OpenFifo()
  64.     returns a fifo handle to be used for further operations.
  65.  
  66.     bufsize must be a power of 2.  For example, 1024.
  67.  
  68.     NOTE: two OpenFifo()s opening the same fifo are NOT guaranteed
  69.     to return the same handle, even though they reference the same
  70.     FIFO.
  71.  
  72.     FLAGS
  73.     FIFOF_READ
  74.         file handle intended to be used for reading, do not specify
  75.         unless you read from the handle.
  76.  
  77.     FIFOF_WRITE
  78.         file handle intended to be used for writing, do not specify
  79.         unless you write to the handle.
  80.  
  81.         If a previous CloseFifo() activated FIFOF_EOF, then the flag is
  82.         cleared.
  83.  
  84.     FIFOF_NORMAL
  85.         normal (task based) calls to library, else is assumed calls
  86.         will be made from an interrupt or hardware exception.
  87.  
  88.         NOTE: non-normal fifo writes are unable to wake up blocked
  89.         library calls.  Thus, anybody reading a fifo written to by
  90.         an interrupt or exception (read: enforcer), must poll the
  91.         fifo.  Eventually automatic polling will be an option to make
  92.         operation with non-normal writers transparent to the reader.
  93.  
  94.     FIFOF_KEEPIFD
  95.         When this FIFO is eventually closed, do not destroy it if
  96.         unread data is pending.  Allows a 'writer' to completely finish
  97.         and exit before a read even has the chance to open the fifo.
  98.  
  99.     FIFOF_RREQUIRED
  100.         Cause any write operations to fail when there are no readers
  101.         (i.e. broken pipe), prevents a lockup from occurring if the
  102.         reader is ^C'd.
  103.  
  104.     FIFOF_NBIO
  105.         Specify that ReadFifo() and WriteFifo() calls are not to block.
  106.  
  107.     BUGS
  108.     FIFOF_EOF is not cleared. EOF is received continuously.
  109.  
  110.  
  111. fifo.library/CloseFifo                      fifo.library/CloseFifo
  112.  
  113.     NAME
  114.     CloseFifo - close a previously opened FIFO
  115.  
  116.     SYNOPSIS
  117.     void CloseFifo(fifo, flags)
  118.             D0     D1
  119.  
  120.     void *fifo;    /*  fifo handle previously returned by OpenFifo() */
  121.     long flags;    /*  see below    */
  122.  
  123.     FUNCTION
  124.     CloseFifo() is the reverse of OpenFifo(), dereferencing a Fifo.
  125.  
  126.     The last close of a shared fifo will result in the deletion of that
  127.     fifo ONLY if all data has been read, allowing unsynchronized
  128.     programs to use the Fifo.
  129.  
  130.     A future flag will cause the last close of a FIFO to delete the
  131.     fifo and throw away any data.
  132.  
  133.     FLAGS
  134.  
  135.     FIFOF_EOF
  136.         If specified, the FIFO will generate an EOF to readers
  137.         after the last writer has closed.  This particular handle
  138.         need not be the last writer.
  139.  
  140.         If not specified, any active readers are left hanging
  141.         (allowing another program to 'take up' where this one left
  142.         off without the readers knowing)
  143.  
  144.         NOTE that any new writer that OpenFifo()s the fifo will
  145.         clear this flag.
  146.  
  147.         NOTE that the EOF condition will be returned only once
  148.         to a given reader, then cleared (causing the reader to
  149.         block again).  This is because shells generally ignore
  150.         EOF and we would otherwise get into an infinite loop.
  151.  
  152.         THIS FLAG HAS NO EFFECT IF THE HANDLE WAS NOT ORIGINALLY
  153.         OPENED FIFOF_WRITE.
  154.  
  155.     BUGS
  156.     The EOF condition is not given once only, but continously (probably
  157.     in an attempt to stop programs), a future flag may address this and
  158.     provide both possibilities.
  159.     A new writer that OpenFifo()s will not clear the FIFOF_EOF flag.
  160.  
  161.  
  162. fifo.library/ReadFifo                      fifo.library/ReadFifo
  163.  
  164.     NAME
  165.     ReadFifo -  read data from a FIFO
  166.  
  167.     SYNOPSIS
  168.     long ready = ReadFifo(fifo, pptr, skip)
  169.            D0           D0    D1   A0
  170.  
  171.     void *fifo;    /*  fifo handle previously returned by OpenFifo() */
  172.     char **pptr;    /*  address of pointer to store buffer pointer      */
  173.     long skip;    /*  # of bytes to skip (delete)     */
  174.     long ready;    /*  # of bytes available to read, -1 = EOF    */
  175.  
  176.     WARNING
  177.     ReadFifo() uses UNCONVENTIONAL ARGUMENTS
  178.  
  179.     FUNCTION
  180.     ReadFifo() first deletes (skip) bytes from the FIFO, then sets a
  181.     pointer into the fifo's buffer and returns the number of bytes
  182.     immediately available for reading.
  183.  
  184.     THE DATA POINTER TO MAY NOT BE MODIFIED UNDER ANY CIRCUMSTANCES
  185.  
  186.     The call is efficient because, in many cases, a buffer copy can be
  187.     completely avoided by the program.  The loop code in the example
  188.     below shows generally how operation works.  For further
  189.     information, refer to the test program (TESTFIFO.C).
  190.  
  191.     The number of bytes available (ready), is independent of the
  192.     number of bytes you threw away (skip).    You get a certain amount
  193.     of lookahead for free, but it should be stressed that the (ready)
  194.     value is not necessarily all the available data.  Data in the
  195.     fifo is not always contiguous and so there may be more data
  196.     available than you can immediately determine.  For example, the
  197.     call might return 1 when in fact 500 bytes are available.  But
  198.     only 1 byte is available contiguously (based at the pointer).
  199.     After processing the 1 byte your next read would return 499.
  200.  
  201.     NON-BLOCKING IO
  202.     If FIFOF_NBIO was specified on open, this call will return
  203.     immediately and 0 is a valid return.  If 0 is returned there
  204.     is no data ready and the program must poll the fifo.  But
  205.     wait, there is a better way to do it ... instead of polling
  206.     the fifo you can opt to have a message sent to you when data
  207.     becomes available.  see the RequestFifo() function call and
  208.     look at TEST.C
  209.  
  210.     If FIFOF_NBIO is *not* specified, then 0 will never be returned
  211.     by this call.  Instead, either >0 or -1 (EOF) will be returned.
  212.  
  213.     MULTIPLE-READERS
  214.  
  215.     Multiple readers may exist for a given FIFO.  This is completely
  216.     supported.  If you have one writer and two readers, and the
  217.     writer writes "ABC", then both readers will each read "ABC".
  218.     Because the FIFO buffer is shared, readers may NOT modify any
  219.     data returned in (pptr) because this could effect other readers
  220.     (depending on whether they have already read the data or not).
  221.  
  222.     INTERRUPTS / EXCEPTIONS
  223.  
  224.     ReadFifo() may not be called from an interrupt or a hardware
  225.     exception.  ReadFifo() may ONLY be called from task or process.
  226.  
  227.     EXAMPLE
  228.  
  229.     /*
  230.      *  dump fifo ff.  FIFO was opened without FIFOF_NBIO.
  231.      */
  232.  
  233.     {
  234.         long i = 0;         /*    delete nothing on first loop  */
  235.         long n;
  236.         char *ptr;
  237.  
  238.         while ((n = ReadFifo(ff, &ptr, i)) > 0) {
  239.         if (n > 64)        /*    can easily limit read-size if you */
  240.             n = 64;        /*    want to (optional, obviously)      */
  241.         i = n;            /*    drain this many on next loop    */
  242.         write(1, ptr, n);
  243.         }
  244.         /*
  245.          *    note, if you break out of the loop you may need a final
  246.          *    ReadFifo(ff, &ptr, i); to clear out what you have already
  247.          *    processed.
  248.          */
  249.     }
  250.  
  251.  
  252. fifo.library/WriteFifo                      fifo.library/WriteFifo
  253.  
  254.     NAME
  255.     WriteFifo - write data to a FIFO
  256.  
  257.     SYNOPSIS
  258.     long actual = WriteFifo(fifo, buf, len)
  259.            D0        D0    D1   A0
  260.  
  261.     void *fifo;    /*  fifo handle previously returned by OpenFifo() */
  262.     void *buf;    /*  buffer to read data into    */
  263.     long max;    /*  maximum # of bytes to read    */
  264.  
  265.     FUNCTION
  266.     WriteFifo() writes data to a FIFO.  WriteFifo() will either return
  267.     actual = len if the write succeeded, 0 if the FIFO is full, or -1
  268.     if an error occurs.  No intermediate values are currently returned
  269.     (i.e. writes are atomic)
  270.  
  271.     If two writers attempt to write to the same FIFO at the same time
  272.     and the FIFOF_NORMAL flag was not specified on open (i.e. writer
  273.     writes from an interrupt or exception), then it is possible for
  274.     a collision to occur in which case one of the calls will return
  275.     an error (-1).
  276.  
  277.     WARNING WARNING
  278.     You may not write blocks larger than 1/2 the fifo buffer size,
  279.     this will generate an immediate error (-2) regardless of how
  280.     much space is actually available.  The reason for this is simply
  281.     that writes are guarenteed to be atomic, and cannot be guarenteed
  282.     if larger blocks are written.  Also, flow control breaks down
  283.     with larger blocks so I figure it is best to nip it in the bud and
  284.     return a formal error.
  285.  
  286.     NON-BLOCKING-IO (FIFOF_NORMAL fifos only)
  287.     Writes are atomic.  If a write fails and FIFOF_NBIO was specified
  288.     on open, the write will return with a failure code of -1.  You
  289.     may optionally poll or use the RequestFifo() call.
  290.  
  291.     Note that even if RequestFifo() returns the message, a write may
  292.     fail due to other processes writing to the fifo before you have
  293.     a chance to, in which case you have to RequestFifo() again and
  294.     loop.
  295.  
  296.     If FIFOF_NBIO was not specified on open, then the write will not
  297.     return until the data has been successfully written, or -2 will
  298.     be returned if you specified too large a buffer.
  299.  
  300.     INTERRUPTS/EXCEPTIONS
  301.     To write to a fifo from an interrupt or exception you must open the
  302.     fifo WITHOUT the FIFOF_NORMAL flag, and be prepared to handle
  303.     possible collisions with other writers.
  304.  
  305.     In this case a failure code of -1 could mean either that the FIFO
  306.     is full or that a collision has occured and you were the side that
  307.     lost out.
  308.  
  309.     WARNING:  any writes via a fifo not opened with the FIFOF_NORMAL
  310.     flag will *NOT* wakeup anybody blocked waiting to read from the
  311.     fifo, whether by RequestFifo() (the message is not returned),
  312.     or via normal opens (without the FIFOF_NBIO flag).  Readers must
  313.     POLL in this case.
  314.  
  315. fifo.library/RequestFifo                fifo.library/RequestFifo
  316.  
  317.     NAME
  318.     RequestFifo - request this message be returned when read data is
  319.               available or write buffer space is available.
  320.  
  321.  
  322.     SYNOPSIS
  323.     RequestFifo(fifo, msg, req)
  324.              D0   D1    A0
  325.  
  326.     void *fifo;
  327.     struct Message *msg;    /*  message in question    */
  328.     long req;        /*  request            */
  329.  
  330.     FUNCTION
  331.     Normally this call is used to queue a message to the fifo.library
  332.     that will be ReplyMsg()d to your task when the specified condition
  333.     occurs.  There are three possible requests.
  334.  
  335.     FREQ_RPEND
  336.         Request that the specified message be returned when read data
  337.         is pending on the fifo.
  338.  
  339.         note: if data is immediately available, the message will be
  340.         immediately replied.  If an EOF condition exists or occurs the
  341.         message will also be replied.
  342.  
  343.     FREQ_WAVAIL
  344.         Request that the specified message be returned when the fifo is
  345.         more than half empty.  It is possible that an attempt to write
  346.         after getting your message back will fail due to other writers
  347.         getting their writes in ahead of you.
  348.  
  349.     FREQ_ABORT
  350.         Request that this message, which was previously queued via
  351.         FREQ_RPEND or FREQ_WAVAIL, be returned immediately.
  352.  
  353.         May be called even if message has already been returned but
  354.         not processed.
  355.  
  356.     You may queue multiple messages, even several messages all for the
  357.     same thing.  When you queue a message, it's node becomes owned by
  358.     the library until replied.  You CANNOT queue the same message
  359.     multiple times at once.  Generally programmers will queue one
  360.     message for write-avail-space and another message for
  361.     read-data-ready, then poll the fifo when these messages are
  362.     returned and re-queue the message(s).
  363.  
  364.     ReadFifo() and WriteFifo() call RequestFifo() internally when the
  365.     FIFOF_NBIO flag is NOT used.  This is how they wait for events when
  366.     a call blocks due to lack of data or lack of buffer space.
  367.  
  368.  
  369. fifo.library/BufSizeFifo                fifo.library/BufSizeFifo
  370.  
  371.     NAME
  372.     BufSizeFifo - return size of fifo's buffer
  373.  
  374.     SYNOPSIS
  375.     long bytes = BufSizeFifo(fifo)
  376.            D0         D0
  377.  
  378.     void *fifo;
  379.  
  380.     FUNCTION
  381.     This function returns the size of the specified fifo's buffer.
  382.  
  383.     Note that you may not make WriteFifo() calls with lengths
  384.     larger than 1/2 the size of the fifo's buffer.  This function
  385.     allows you to determine the fifo's buffer size to properly
  386.     observe this limit.  You cannot depend on the buffer size you
  387.     specified in OpenFifo() because only the first OpenFifo() for
  388.     a given fifo actually sets the buffer size.
  389.  
  390.  
  391.